Skip to main content
Version: 2.4.x

该功能特性从 v2.5 版本开始提供。该命令目前仅支持 HTTP 接口开发, GRPC 部分请参考 gen pb 命令。未来会考虑 HTTPGRPC 统一使用该命令生成控制器及 SDK 源代码。

基本介绍

解决痛点

在开发项目的时候,往往需要先根据业务需求和场景设计 API 接口,使用 proto 或者 golang struct 来设计 API 的输入和输出,随后再创建与 API 相对应的控制器实现,最后也有可能会提供 SDK(同为 Golang 语言条件下)供内/外部服务调用。在开发过程中会遇到以下痛点:

  • 重复的代码工作较多。在 API 中创建输入输出定义文件后还需要在控制器目录下创建对应的文件、创建对应的控制器初始化代码、从 API 代码中反复拷贝各个输入输出结构名称,在这过程重复的操作比较多。
  • API与控制器之间的关联没有可靠规范约束。除了 API 有一定的命名约束外,控制器的创建和方法命名并没有约束,灵活度较高, API 的结构名称与控制器方法名称难以约束对应,当接口越来越多时会有一定维护成本。
  • 缺少API的HTTP SDK自动生成工具。当开发完 API 后,往往需要立即给内部或者外部调用,缺少便捷的 SDK 生成,需要手动来维护这部分 SDK 代码,那么对于调用端来说成本非常高。

命令特性

  • 规范关联 API 定义与控制器文件命名、控制器实现方法命名。
  • 根据 API 定义自动生成控制器接口、控制器初始化文件及代码、接口初始化代码。
  • 根据 API 定义自动生成易于使用的 HTTP SDK 代码。
  • 支持自动化生成模式:当某个 API 结构定义文件发生变化时,自动增量化更新对应的控制器、 SDK 代码。

命令使用

该命令通过分析给定的 api 接口定义目录下的代码,自动生成对应的控制器/ SDK Go 代码文件。

手动模式

如果是手动执行命令行,直接在项目根目录下执行 gf gen ctrl 即可,她将完整扫描 api 接口定义目录,并生成对应代码。

$ gf gen ctrl -h
USAGE
gf gen ctrl [OPTION]

OPTION
-s, --srcFolder source folder path to be parsed. default: api
-d, --dstFolder destination folder path storing automatically generated go files. default: internal/controller
-w, --watchFile used in file watcher, it re-generates go files only if given file is under srcFolder
-k, --sdkPath also generate SDK go files for api definitions to specified directory
-v, --sdkStdVersion use standard version prefix for generated sdk request path
-n, --sdkNoV1 do not add version suffix for interface module name if version is v1
-h, --help more information about this command

EXAMPLE
gf gen ctrl

如果使用框架推荐的项目工程脚手架,并且系统安装了 make 工具,也可以使用 make ctrl 快捷指令。

参数说明:

名称必须默认值含义
srcFolderapi指向 api 接口定义文件目录地址
dstFolderinternal/controller指向生成的控制器文件存放目录
watchFile用在IDE的文件监控中,用于根据当文件发生变化时自动执行生成操作
sdkPath如果需要生成 HTTP SDK,该参数用于指定生成的SDK代码目录存放路径
sdkStdVersion生成的 HTTP SDK 是否使用标准的版本管理。标准的版本管理将自动根据 API 版本增加请求的路由前缀。例如 v1 版本的API将会自动增加 /api/v1 的请求路由前缀。
sdksdkNoV1生成的 HTTP SDK 中,当接口为 v1 版本时,接口模块名称是否不带 V1 后缀。

自动模式(推荐)

如果您是使用的 GolandIDE,那么可以使用我们提供的配置文件: watchers.xml  自动监听代码文件修改时自动生成接口文件。使用方式,如下图:

使用示例

自动生成的接口定义文件

自动生成的控制器代码文件

自动生成的 HTTP SDK 代码文件